package com.cencat.route.service;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.cencat.route.entity.Delivery;
import com.cencat.route.vo.DeliveryVO;
import com.cencat.route.dto.DeliveryDTO;
import com.cencat.route.dto.DeliveryQueryDTO;
import com.cencat.route.dto.DeliveryBatchUpdateDTO;
import com.cencat.route.dto.DeliveryStatisticsDTO;
import com.cencat.route.dto.DeliveryMatchDTO;
import jakarta.validation.constraints.NotNull;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 配送管理服务接口
 * 提供配送的增删改查、统计分析、智能匹配等业务功能
 * 
 * @author cencat
 * @version 1.0
 * @since 2025-01-20
 */
public interface DeliveryService {

    /**
     * 分页查询配送列表
     * 
     * @param page 分页参数
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    Page<DeliveryVO> getDeliveryList(Page<Delivery> page, DeliveryQueryDTO queryDTO);

    /**
     * 根据ID获取配送详情
     * 
     * @param id 配送ID
     * @return 配送详情
     */
    DeliveryVO getDeliveryById(@NotNull Long id);

    /**
     * 创建新配送
     * 
     * @param deliveryDTO 配送信息
     * @return 创建结果
     */
    Boolean createDelivery(@NotNull DeliveryDTO deliveryDTO);

    /**
     * 更新配送信息
     * 
     * @param id 配送ID
     * @param deliveryDTO 配送信息
     * @return 更新结果
     */
    Boolean updateDelivery(@NotNull Long id, @NotNull DeliveryDTO deliveryDTO);

    /**
     * 删除配送
     * 
     * @param id 配送ID
     * @return 删除结果
     */
    Boolean deleteDelivery(@NotNull Long id);

    /**
     * 批量删除配送
     * 
     * @param ids 配送ID列表
     * @return 删除结果
     */
    Boolean batchDeleteDeliveries(@NotNull List<Long> ids);

    /**
     * 批量更新配送状态
     * 
     * @param batchUpdateDTO 批量更新参数
     * @return 更新结果
     */
    Boolean batchUpdateDeliveryStatus(@NotNull DeliveryBatchUpdateDTO batchUpdateDTO);

    /**
     * 批量更新配送优先级
     * 
     * @param ids 配送ID列表
     * @param priority 优先级
     * @return 更新结果
     */
    Boolean batchUpdatePriority(@NotNull List<Long> ids, @NotNull Integer priority);

    /**
     * 批量分配配送员
     * 
     * @param ids 配送ID列表
     * @param deliveryManId 配送员ID
     * @return 分配结果
     */
    Boolean batchAssignDeliveryMan(@NotNull List<Long> ids, @NotNull Long deliveryManId);

    /**
     * 批量更新配送费用
     * 
     * @param ids 配送ID列表
     * @param deliveryFee 配送费用
     * @return 更新结果
     */
    Boolean batchUpdateDeliveryFee(@NotNull List<Long> ids, @NotNull Double deliveryFee);

    /**
     * 获取配送统计信息
     * 
     * @param statisticsDTO 统计参数
     * @return 统计结果
     */
    Map<String, Object> getDeliveryStatistics(@NotNull DeliveryStatisticsDTO statisticsDTO);

    /**
     * 智能匹配配送
     * 
     * @param matchDTO 匹配参数
     * @return 匹配结果
     */
    List<DeliveryVO> intelligentMatchDeliveries(@NotNull DeliveryMatchDTO matchDTO);

    /**
     * 获取紧急配送
     * 
     * @param limit 数量限制
     * @return 紧急配送列表
     */
    List<DeliveryVO> getUrgentDeliveries(@NotNull Integer limit);

    /**
     * 获取待配送订单
     * 
     * @param limit 数量限制
     * @return 待配送订单列表
     */
    List<DeliveryVO> getPendingDeliveries(@NotNull Integer limit);

    /**
     * 获取配送中订单
     * 
     * @param limit 数量限制
     * @return 配送中订单列表
     */
    List<DeliveryVO> getInTransitDeliveries(@NotNull Integer limit);

    /**
     * 获取已完成配送
     * 
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @param limit 数量限制
     * @return 已完成配送列表
     */
    List<DeliveryVO> getCompletedDeliveries(@NotNull LocalDateTime startTime, @NotNull LocalDateTime endTime, 
                                            @NotNull Integer limit);

    /**
     * 获取超时配送
     * 
     * @param limit 数量限制
     * @return 超时配送列表
     */
    List<DeliveryVO> getOverdueDeliveries(@NotNull Integer limit);

    /**
     * 获取配送员配送列表
     * 
     * @param deliveryManId 配送员ID
     * @param status 状态
     * @param limit 数量限制
     * @return 配送员配送列表
     */
    List<DeliveryVO> getDeliveryManDeliveries(@NotNull Long deliveryManId, String status, @NotNull Integer limit);

    /**
     * 获取区域配送列表
     * 
     * @param areaCode 区域编码
     * @param status 状态
     * @param limit 数量限制
     * @return 区域配送列表
     */
    List<DeliveryVO> getAreaDeliveries(@NotNull String areaCode, String status, @NotNull Integer limit);

    /**
     * 获取商户配送列表
     * 
     * @param merchantId 商户ID
     * @param status 状态
     * @param limit 数量限制
     * @return 商户配送列表
     */
    List<DeliveryVO> getMerchantDeliveries(@NotNull Long merchantId, String status, @NotNull Integer limit);

    /**
     * 检查配送是否存在
     * 
     * @param id 配送ID
     * @return 是否存在
     */
    Boolean existsById(@NotNull Long id);

    /**
     * 检查配送单号是否存在
     * 
     * @param deliveryNo 配送单号
     * @param excludeId 排除的配送ID
     * @return 是否存在
     */
    Boolean existsByDeliveryNo(@NotNull String deliveryNo, Long excludeId);

    /**
     * 分配配送员
     * 
     * @param deliveryId 配送ID
     * @param deliveryManId 配送员ID
     * @return 分配结果
     */
    Boolean assignDeliveryMan(@NotNull Long deliveryId, @NotNull Long deliveryManId);

    /**
     * 开始配送
     * 
     * @param deliveryId 配送ID
     * @return 开始结果
     */
    Boolean startDelivery(@NotNull Long deliveryId);

    /**
     * 完成配送
     * 
     * @param deliveryId 配送ID
     * @param signatureImage 签收图片
     * @return 完成结果
     */
    Boolean completeDelivery(@NotNull Long deliveryId, String signatureImage);

    /**
     * 取消配送
     * 
     * @param deliveryId 配送ID
     * @param reason 取消原因
     * @return 取消结果
     */
    Boolean cancelDelivery(@NotNull Long deliveryId, @NotNull String reason);

    /**
     * 配送异常处理
     * 
     * @param deliveryId 配送ID
     * @param exceptionType 异常类型
     * @param exceptionReason 异常原因
     * @return 处理结果
     */
    Boolean handleDeliveryException(@NotNull Long deliveryId, @NotNull String exceptionType, 
                                    @NotNull String exceptionReason);

    /**
     * 重新分配配送员
     * 
     * @param deliveryId 配送ID
     * @param newDeliveryManId 新配送员ID
     * @param reason 重新分配原因
     * @return 重新分配结果
     */
    Boolean reassignDeliveryMan(@NotNull Long deliveryId, @NotNull Long newDeliveryManId, 
                                @NotNull String reason);

    /**
     * 获取配送进度
     * 
     * @param deliveryId 配送ID
     * @return 进度信息
     */
    Map<String, Object> getDeliveryProgress(@NotNull Long deliveryId);

    /**
     * 更新配送进度
     * 
     * @param deliveryId 配送ID
     * @param progress 进度百分比
     * @param currentLocation 当前位置
     * @param estimatedArrival 预计到达时间
     * @return 更新结果
     */
    Boolean updateDeliveryProgress(@NotNull Long deliveryId, @NotNull Integer progress, 
                                   @NotNull String currentLocation, LocalDateTime estimatedArrival);

    /**
     * 获取配送路径
     * 
     * @param deliveryId 配送ID
     * @return 配送路径
     */
    List<Map<String, Object>> getDeliveryRoute(@NotNull Long deliveryId);

    /**
     * 优化配送路径
     * 
     * @param deliveryId 配送ID
     * @return 优化结果
     */
    Boolean optimizeDeliveryRoute(@NotNull Long deliveryId);

    /**
     * 计算配送费用
     * 
     * @param deliveryId 配送ID
     * @return 配送费用
     */
    Double calculateDeliveryFee(@NotNull Long deliveryId);

    /**
     * 获取配送时效
     * 
     * @param deliveryId 配送ID
     * @return 配送时效信息
     */
    Map<String, Object> getDeliveryTimeLimit(@NotNull Long deliveryId);

    /**
     * 获取配送评价
     * 
     * @param deliveryId 配送ID
     * @return 配送评价
     */
    Map<String, Object> getDeliveryRating(@NotNull Long deliveryId);

    /**
     * 提交配送评价
     * 
     * @param deliveryId 配送ID
     * @param rating 评分
     * @param comment 评价内容
     * @return 提交结果
     */
    Boolean submitDeliveryRating(@NotNull Long deliveryId, @NotNull Integer rating, String comment);

    /**
     * 导出配送数据
     * 
     * @param queryDTO 查询条件
     * @return 导出数据
     */
    List<DeliveryVO> exportDeliveries(@NotNull DeliveryQueryDTO queryDTO);

    /**
     * 导入配送数据
     * 
     * @param deliveries 配送数据列表
     * @return 导入结果
     */
    Boolean importDeliveries(@NotNull List<DeliveryDTO> deliveries);

    /**
     * 自动分配配送员
     * 
     * @param deliveryId 配送ID
     * @param requirements 需求条件
     * @return 自动分配结果
     */
    Boolean autoAssignDeliveryMan(@NotNull Long deliveryId, @NotNull String requirements);

    /**
     * 批量优化配送路径
     * 
     * @param deliveryIds 配送ID列表
     * @return 优化结果
     */
    Boolean batchOptimizeDeliveryRoutes(@NotNull List<Long> deliveryIds);
}